home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_apache2.idb / usr / freeware / apache2 / include / apr_strings.h.z / apr_strings.h
C/C++ Source or Header  |  2002-07-08  |  13KB  |  344 lines
  1. /* ====================================================================
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Apache" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  */
  54.  
  55. /* Portions of this file are covered by */
  56. /* -*- mode: c; c-file-style: "k&r" -*-
  57.  
  58.   strnatcmp.c -- Perform 'natural order' comparisons of strings in C.
  59.   Copyright (C) 2000 by Martin Pool <mbp@humbug.org.au>
  60.  
  61.   This software is provided 'as-is', without any express or implied
  62.   warranty.  In no event will the authors be held liable for any damages
  63.   arising from the use of this software.
  64.  
  65.   Permission is granted to anyone to use this software for any purpose,
  66.   including commercial applications, and to alter it and redistribute it
  67.   freely, subject to the following restrictions:
  68.  
  69.   1. The origin of this software must not be misrepresented; you must not
  70.      claim that you wrote the original software. If you use this software
  71.      in a product, an acknowledgment in the product documentation would be
  72.      appreciated but is not required.
  73.   2. Altered source versions must be plainly marked as such, and must not be
  74.      misrepresented as being the original software.
  75.   3. This notice may not be removed or altered from any source distribution.
  76. */
  77.  
  78. #ifndef APR_STRINGS_H
  79. #define APR_STRINGS_H
  80.  
  81. #include "apr.h"
  82. #include "apr_errno.h"
  83. #include "apr_pools.h"
  84. #define APR_WANT_IOVEC
  85. #include "apr_want.h"
  86.  
  87. #if APR_HAVE_STDARG_H
  88. #include <stdarg.h>
  89. #endif
  90.  
  91. #ifdef __cplusplus
  92. extern "C" {
  93. #endif /* __cplusplus */
  94. /**
  95.  * @file apr_strings.h
  96.  * @brief APR Strings library
  97.  */
  98. /**
  99.  * @defgroup APR_Strings String routines
  100.  * @ingroup APR
  101.  * @{
  102.  */
  103. /**
  104.  * Do a natural order comparison of two strings.
  105.  * @param a The first string to compare
  106.  * @param b The second string to compare
  107.  * @return Either <0, 0, or >0.  If the first string is less than the second
  108.  *          this returns <0, if they are equivalent it returns 0, and if the
  109.  *          first string is greater than second string it retuns >0.
  110.  */
  111. APR_DECLARE(int) apr_strnatcmp(char const *a, char const *b);
  112.  
  113. /**
  114.  * Do a natural order comparison of two strings ignoring the case of the 
  115.  * strings.
  116.  * @param a The first string to compare
  117.  * @param b The second string to compare
  118.  * @return Either <0, 0, or >0.  If the first string is less than the second
  119.  *         this returns <0, if they are equivalent it returns 0, and if the
  120.  *         first string is greater than second string it retuns >0.
  121.  */
  122. APR_DECLARE(int) apr_strnatcasecmp(char const *a, char const *b);
  123.  
  124. /**
  125.  * duplicate a string into memory allocated out of a pool
  126.  * @param p The pool to allocate out of
  127.  * @param s The string to duplicate
  128.  * @return The new string
  129.  */
  130. APR_DECLARE(char *) apr_pstrdup(apr_pool_t *p, const char *s);
  131.  
  132. /**
  133.  * Create a null-terminated string by making a copy of a sequence
  134.  * of characters and appending a null byte
  135.  * @param p The pool to allocate out of
  136.  * @param s The block of characters to duplicate
  137.  * @param n The number of characters to duplicate
  138.  * @return The new string
  139.  * @remark This is a faster alternative to apr_pstrndup, for use
  140.  *         when you know that the string being duplicated really
  141.  *         has 'n' or more characters.  If the string might contain
  142.  *         fewer characters, use apr_pstrndup.
  143.  */
  144. APR_DECLARE(char *) apr_pstrmemdup(apr_pool_t *p, const char *s, apr_size_t n);
  145.  
  146. /**
  147.  * duplicate the first n characters of a string into memory allocated 
  148.  * out of a pool; the new string will be '\0'-terminated
  149.  * @param p The pool to allocate out of
  150.  * @param s The string to duplicate
  151.  * @param n The number of characters to duplicate
  152.  * @return The new string
  153.  */
  154. APR_DECLARE(char *) apr_pstrndup(apr_pool_t *p, const char *s, apr_size_t n);
  155.  
  156. /**
  157.  * Duplicate a block of memory.
  158.  *
  159.  * @param p The pool to allocate from
  160.  * @param m The memory to duplicate
  161.  * @param n The number of bytes to duplicate
  162.  * @return The new block of memory
  163.  */
  164. APR_DECLARE(void *) apr_pmemdup(apr_pool_t *p, const void *m, apr_size_t n);
  165.  
  166. /**
  167.  * Concatenate multiple strings, allocating memory out a pool
  168.  * @param p The pool to allocate out of
  169.  * @param ... The strings to concatenate.  The final string must be NULL
  170.  * @return The new string
  171.  */
  172. APR_DECLARE_NONSTD(char *) apr_pstrcat(apr_pool_t *p, ...);
  173.  
  174. /**
  175.  * Concatenate multiple strings specified in a writev-style vector
  176.  * @param p The pool from which to allocate
  177.  * @param vec The strings to concatenate
  178.  * @param nvec The number of strings to concatenate
  179.  * @param nbytes (output) strlen of new string (pass in NULL to omit)
  180.  * @return The new string
  181.  */
  182. APR_DECLARE_NONSTD(char *) apr_pstrcatv(apr_pool_t *p, const struct iovec *vec,
  183.                                         apr_size_t nvec, apr_size_t *nbytes);
  184.  
  185. /**
  186.  * printf-style style printing routine.  The data is output to a string 
  187.  * allocated from a pool
  188.  * @param p The pool to allocate out of
  189.  * @param fmt The format of the string
  190.  * @param ap The arguments to use while printing the data
  191.  * @return The new string
  192.  */
  193. APR_DECLARE(char *) apr_pvsprintf(apr_pool_t *p, const char *fmt, va_list ap);
  194.  
  195. /**
  196.  * printf-style style printing routine.  The data is output to a string 
  197.  * allocated from a pool
  198.  * @param p The pool to allocate out of
  199.  * @param fmt The format of the string
  200.  * @param ... The arguments to use while printing the data
  201.  * @return The new string
  202.  */
  203. APR_DECLARE_NONSTD(char *) apr_psprintf(apr_pool_t *p, const char *fmt, ...)
  204.         __attribute__((format(printf,2,3)));
  205.  
  206. /**
  207.  * copy n characters from src to dst
  208.  * @param dst The destination string
  209.  * @param src The source string
  210.  * @param dst_size The space available in dst; dst always receives
  211.  *                 null-termination, so if src is longer than
  212.  *                 dst_size, the actual number of characters copied is
  213.  *                 dst_size - 1.
  214.  * @remark
  215.  * <PRE>
  216.  * We re-implement this function to implement these specific changes:
  217.  *       1) strncpy() doesn't always null terminate and we want it to.
  218.  *       2) strncpy() null fills, which is bogus, esp. when copy 8byte strings
  219.  *          into 8k blocks.
  220.  *       3) Instead of returning the pointer to the beginning of the
  221.  *          destination string, we return a pointer to the terminating '\0'
  222.  *          to allow us to check for truncation.
  223.  * </PRE>
  224.  */
  225. APR_DECLARE(char *) apr_cpystrn(char *dst, const char *src,
  226.                                 apr_size_t dst_size);
  227.  
  228. /**
  229.  * Strip spaces from a string
  230.  * @param dest The destination string.  It is okay to modify the string
  231.  *             in place.  Namely dest == src
  232.  * @param src The string to rid the spaces from.
  233.  */
  234. APR_DECLARE(char *) apr_collapse_spaces(char *dest, const char *src);
  235.  
  236. /**
  237.  * Convert the arguments to a program from one string to an array of 
  238.  * strings terminated by a NULL pointer
  239.  * @param str The arguments to convert
  240.  * @param argv_out Output location.  This is a pointer to an array of strings.
  241.  * @param token_context Pool to use.
  242.  */
  243. APR_DECLARE(apr_status_t) apr_tokenize_to_argv(const char *arg_str,
  244.                                                char ***argv_out,
  245.                                                apr_pool_t *token_context);
  246.  
  247. /**
  248.  * Split a string into separate '\0'-terminated tokens.  The tokens are 
  249.  * delimited in the string by one or more characters from the sep
  250.  * argument.
  251.  * @param str The string to separate; this should be specified on the
  252.  *            first call to apr_strtok() for a given string, and NULL
  253.  *            on subsequent calls.
  254.  * @param sep The set of delimiters
  255.  * @param last Internal state saved by apr_strtok() between calls.
  256.  * @return The next token from the string
  257.  */
  258. APR_DECLARE(char *) apr_strtok(char *str, const char *sep, char **last);
  259.  
  260. /**
  261.  * @defgroup APR_Strings_Snprintf snprintf implementations
  262.  *
  263.  * @warning
  264.  * These are snprintf implementations based on apr_vformatter().
  265.  *
  266.  * Note that various standards and implementations disagree on the return
  267.  * value of snprintf, and side-effects due to %n in the formatting string.
  268.  * apr_snprintf behaves as follows:
  269.  *
  270.  * Process the format string until the entire string is exhausted, or
  271.  * the buffer fills.  If the buffer fills then stop processing immediately
  272.  * (so no further %n arguments are processed), and return the buffer
  273.  * length.  In all cases the buffer is NUL terminated.
  274.  *
  275.  * In no event does apr_snprintf return a negative number.  It's not possible
  276.  * to distinguish between an output which was truncated, and an output which
  277.  * exactly filled the buffer.
  278.  * @{
  279.  */
  280.  
  281. /**
  282.  * snprintf routine based on apr_vformatter.  This means it understands the
  283.  * same extensions.
  284.  * @param buf The buffer to write to
  285.  * @param len The size of the buffer
  286.  * @param format The format string
  287.  * @param ... The arguments to use to fill out the format string.
  288.  */
  289. APR_DECLARE_NONSTD(int) apr_snprintf(char *buf, apr_size_t len,
  290.                                      const char *format, ...)
  291.         __attribute__((format(printf,3,4)));
  292.  
  293. /**
  294.  * vsnprintf routine based on apr_vformatter.  This means it understands the
  295.  * same extensions.
  296.  * @param buf The buffer to write to
  297.  * @param len The size of the buffer
  298.  * @param format The format string
  299.  * @param ap The arguments to use to fill out the format string.
  300.  */
  301. APR_DECLARE(int) apr_vsnprintf(char *buf, apr_size_t len, const char *format,
  302.                                va_list ap);
  303.  
  304. /** @} */
  305. /**
  306.  * create a string representation of an int, allocated from a pool
  307.  * @param p The pool from which to allocate
  308.  * @param n The number to format
  309.  * @return The string representation of the number
  310.  */
  311. APR_DECLARE(char *) apr_itoa(apr_pool_t *p, int n);
  312.  
  313. /**
  314.  * create a string representation of a long, allocated from a pool
  315.  * @param p The pool from which to allocate
  316.  * @param n The number to format
  317.  * @return The string representation of the number
  318.  */
  319. APR_DECLARE(char *) apr_ltoa(apr_pool_t *p, long n);
  320.  
  321. /**
  322.  * create a string representation of an apr_off_t, allocated from a pool
  323.  * @param p The pool from which to allocate
  324.  * @param n The number to format
  325.  * @return The string representation of the number
  326.  */
  327. APR_DECLARE(char *) apr_off_t_toa(apr_pool_t *p, apr_off_t n);
  328.  
  329. /**
  330.  * Format a binary size (magnitiudes are 2^10 rather than 10^3) from an apr_off_t,
  331.  * as bytes, K, M, T, etc, to a four character compacted human readable string.
  332.  * @param size The size to format
  333.  * @param buf The 5 byte text buffer (counting the trailing null)
  334.  * @return The buf passed to apr_strfsize()
  335.  * @remark All negative sizes report '  - ', apr_strfsize only formats positive values.
  336.  */
  337. APR_DECLARE(char *) apr_strfsize(apr_off_t size, char *buf);
  338. /** @} */
  339. #ifdef __cplusplus
  340. }
  341. #endif
  342.  
  343. #endif  /* !APR_STRINGS_H */
  344.